home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
L' Effet Pommier 3
/
L'Effet Pommier - Volume 03.iso
/
Graphismes
/
3D
/
POV-Ray 3.0B5a PPC
/
POV-Ray 3.0B5a
/
POVDOC.Documentation
/
POV-Ray 3 Mac Docs
< prev
next >
Wrap
Text File
|
1996-02-20
|
46KB
|
820 lines
POV-Ray 3.0
for the
Macintosh
The Very Best
Freeware Macintosh Ray Tracer
Version 3.0 Beta 5a
February 20, 1996
\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
NOTES:
-This beta software is metered, and will expire April 1996.
-This documentation is a quick collection of the old 2.2 Mac docs,
and is being converted to 3.0 information. I'm working from the
top down, so good stuff is at the top, stale stuff is at the end.
--Eduard Schwan
/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
Welcome to POV-Ray for the Macintosh! This software is called a ray tracer. POV-Ray reads a text file
that contains information describing the objects and lighting in a scene, and it generates an image of that
scene from the view point of a camera also described in the text file. The creation of these images and
animations by ray tracing is not a fast process by any means, but it produces very high quality images with
realistic reflections, shading, perspective, and other effects. This program is Freeware. For more
information on the usage and distribution policies of POV-Ray, please see POVLEGAL.DOC.
Introduction
This document describes the specific functions of the Macintosh version of POV-Ray. You will also need
to read the POVRAY.DOC file, which describes the general operation of POV-Ray, and describes its
features and language.
Compatibility
Here are POV-Ray's requirements of hardware and software, and some of its features:
Minimum daily requirements for 68K Macintosh:
68020/68030/68040 CPU (e.g., Mac II, Centris, Quadra, etc.)
68881 Floating Point Unit (FPU) required (Can use Software FPU instead)
System 7
Minimum 8 MB RAM in computer
Minimum daily requirements for Power Macintosh:
601/603/604 PPC CPU (e.g., 6100, 7200, 8500, 9500, etc.)
System 7
Minimum 16 MB RAM in computer
Features:
Saves final images as 24-bit PICT files (and Targa, PNG, or Unix PPM files)
Can create animation image sequences for making Director or QuickTime movies
System 7 Savvy
Accelerated for Power Macintosh
Built-in mini text editor with multiple undo, for editing scene files
╥Templates╙ allow instant inserting of any scene elements into file
Works with System 7's Virtual Memory
Intelligent support of multiple monitors (dialogs follow the Status Window)
Can run in the background, background cooperation is configurable
Auto-Shutdown feature, can auto-save and shut down Mac when rendering is done
Handles System 7 Required AppleEvents
Multiple source files can be dropped on to do batch rendering
Can add System 7 custom Finder icons to rendered PICT files
<??System 7 Balloon Help throughout?? - to do>
Status window contents can be copied to clipboard or saved to text file
<??Can optionally QuickTime-compress final PICT files?? - to do>
Where do I start?
To get started right away, follow the steps 1 through 4. These will guide you through installing the
software, configuring it, and creating your first ray traced picture.
1. Install
First, you must determine which application you need for your Macintosh... do you have a Power
Macintosh? If so, you should get the POVPMAC.SIT archive, otherwise get the POVMAC68.SIT
archive.
Decide where to install POV-Ray and its associated files. There are no restrictions on where the files can
go, but you will need to insure you have enough available disk space to install. The archives are fairly
large, and the extracted files and directories are quite a bit larger still. The archives are "Stuffit" format
files, which means that you will need a copy of Stuffit Expander 3.5 (freeware), Stuffit Lite 3.5
(shareware), or Stuffit Deluxe (commercial) from Aladdin Systems to expand the archives.
The following table will give you an idea of how much free hard disk space you will need for expanding
the archives:
Archive Name Archive Size Expands to about
----------- ------------ ----------------
POVPMAC.SEA 1.2 MBytes 4 MBytes
POVMAC.SEA 1.2 MBytes 4 MBytes
POVMSRC.SEA 600 KBytes 2.2 MBytes
So, as a bare minimum, you will need about 4 MBytes free for the POV-Ray folder.
Now extract the POV-Ray application from the POVPMAC (or POVMAC68) archive using your favorite
Stuffit tool. It would be a good idea to open the POVDOC.Documentation folder and do a quick browse
of the first part of the POVRAY.DOC manual now, before going too much farther.
2. Configure
POV-Ray 3.0 automatically configures itself to your Macintosh, so there is not much you need to do prior
to running it. If you will be rendering large (800x600 or bigger) images, or moving the INCLUDE folder
from its current home in the POVDOC folder, then you will need to read "Advanced Topics" later in this
document.
3. Double-click
You are now ready to run POV-Ray. To render an existing source file, like one of the demo or sample
files, do the following:
3a. Double-click POV-Ray and use ╥Open╙ from the File menu to open the scene file. Under System 7,
you can also drag the source file over and drop it onto the POV-Ray application. This will run POV-
Ray and automatically open the source file. Note that the POV-Ray editor can only open ONE
source file at a time. If you drop multiple files onto POV-Ray, it will start automatically rendering
each file and saving each image to a separate image file. This is another great feature in itself, but
probably not what you wanted to do just yet! This ╥batch-rendering╙ feature is covered in the file
"POV-Ray 2.0 Notes", under Advanced Tips.
3b. Choose ╥Rendering Options╙ from the Render menu, and fill out the dialog with the options you
want (see POVRAY.DOC or use System 7 Balloon Help for more information on these.) For now,
you may want to choose the ╥32x32╙ or ╥64x64╙ image presets from the popup menu, to pick a
small, quick render.
3c. Choose the ╥View╙ - ╥Normal╙ item from the ╥Image╙ menu, so the output image is shown as it
renders.
3d. Choose ╥Render╙ from the Render menu, and POV-Ray will read and ╥parse╙ the source file, and
then create an output image.
3e. When it completes, you may copy the image to the clipboard. Make sure the image window is in
front, and select ╥Copy╙ from the Edit menu. You can also save the image as a PICT file, by
choosing ╥Save╙ or ╥Save As╙ from the File menu.
##### or, for the more adventurous ######
4. Create a New Scene File
To create a new source file of your own, just double-click POV-Ray, or choose ╥New╙ from POV-Ray's
File menu if it is already running. You are presented with an ╥Untitled.POV╙ Source window, and the
Status window. You would then do the following to create and render a new file:
4a. Type some POV-Ray source statements into the Source window. A very useful built-in aid for
automating this is an item hiding under the Edit menu, ╥Insert Template╙. This hierarchical menu
contains syntactically correct ready-to-use text for every POV-Ray statement. You just choose one
(camera, light_source, texture, sphere, etc.) and it will insert it right into your source file wherever
your cursor is. You just edit the parameters after that to tailor it.
4b. Save the file to disk (choose ╥Save╙ under the File menu). Note that the renderer expects the file to
be saved to disk, and you cannot set the rendering options or start rendering until you do this.
4c. Choose ╥Rendering Options╙ from the Render menu, and fill out the dialog with the options you
want. See the "Rendering Options" section of the POV-Ray 2.0 Notes document for more
information on this dialog.
4d. Choose the ╥View╙ - ╥Normal Size╙ item from the Image menu.
4e. Now choose ╥Render╙ from the Render menu, and your source file will be read and ╥parsed╙, and if
there were no errors, an output image will start to be generated.
4f. If POV-Ray finds an error in your source file, it will display an error dialog, write a description of
the error to the Status window, and automatically select the source line in error, for you to fix. You
can fix the line, save the updated file to disk (press command-S), and re-render the scene.
Other Files
In addition to the application, you should also find other POV-Ray archives with the following contents:
POVSRC.SEA - Think C, Metrowerks, and MPW C compatible Macintosh Source Code for POV-Ray.
Macintosh Program Notes
Following is a hodge-podge of information on the Macintosh-specifics of this program.
User Interface
The implementation of POV-Ray on the Macintosh is quite a leap from the command-line interface of
POV-Ray on most other platforms. The core code of POV-Ray is identical (including the command line
parameter passing), but all of that is hidden from the user, and a more convenient ╥Graphical User
Interface╙ is provided, with all the menus, windows and dialog boxes you'd expect from a serious
Macintosh application.
Memory Size
Ray tracing generally uses a LOT of RAM memory to store all the elements of a scene. POV-Ray Mac
initially comes with an application memory size set at 3,000 Kilobytes. This size is sufficient to render all
of the standard example files with room to spare. For less complex images, POV-Ray can render small
scenes effectively in a memory partition as small as 1,000K. The vast majority of the example scene files
will render in 2,000K. To change POV's memory size, click once on the POV-Ray program icon from the
Finder, then choose ╥Get Info╙ from the File menu. The (preferred) application memory size is in a box in
the lower right corner of the window, and can be edited. The value is in Kilobytes, so for example, to
change it to 6 megabytes (approximately 6,000 Kilobytes,) you would enter 6000.
The Windows
POV-Ray Mac has three windows. The ╥Status╙ Window shows progress and statistics during the
rendering process. The ╥Source╙ Window shows the scene text file to be rendered, and acts as a simple
text editor. The ╥Image╙ Window is where the final image is generated during rendering. Text from the
Status and Source windows can be copied and pasted via the clipboard, and the picture in the Image
window can also be copied to the clipboard.
NOTE: When creating a new untitled source file, you must first save it to a disk file before you can set its
options or render it.
Output Image Memory
POV-Ray tries to store the output image entirely in RAM memory while rendering. Since the image
requires approximately Width x Height x 4 bytes of memory, sometimes this is not possible. For
example, a 640 x 480 image needs about 1.25 megabytes of RAM. When POV-Ray finds that it can not
hold the image in RAM, it will hold it in a temporary disk file, and swap it in to a smaller RAM buffer a
few scan-lines at a time. This lets you create very large (4096x4096 theoretically!) images with limited
RAM, at the cost of slower rendering time and more disk I/O. This is referred to in POV-Ray Mac as the
╥Virtual Image Buffer╙ or VIB. To avoid increased wear and tear on your hard disk, and to speed up
rendering times on large images, you can allocate more application memory to POV-Ray, to avoid the use
of the Virtual Image Buffer. If you do not have enough memory in your Mac and must use it, you can
speed things up some by hiding the image window while it renders.
Output image Disk Space
The final images require a fair amount of disk space as well. A final 640x480 PICT image file can take up
to 500 KBytes on disk. If you turn on the "Create Targa Output File" option in the File Rendering
Preferences, this separate Targa file can take an additional 1 MByte for a 640x480 image. Keep this in
mind so you don't run out of disk space before the image completes.
System 7 Virtual Memory Delays
If you are using System 7's virtual memory (VM), particularly for extremely complex scenes, you may
notice very large delays during parsing. This is due to the way the memory allocation, the parser, and
Apple's VM system interact. Once parsing has finished, actual rendering time should be fairly comparable
to non-VM systems.
Preference files and Virtual Image Buffer (VIB) files
POV-Ray automatically creates two special types of files during its operation. The first is ╥POV-Ray
Preferences,╙ which is a small file which will be put inside your System Folder (in the Preferences folder
if you use System 7.) It should be left there, as it stores important user settings for POV-Ray. These
settings can be changed by choosing the POV-Ray Preferences menu item in the Edit menu. If this file is
moved or deleted, POV-Ray will create a new one with default values. One of the things that will need to
be reconfigured if this happens is the ╥Include Paths╙ settings. The other file is called ╥POV-Ray.vib,╙
which is only used during rendering of large images. This is the Virtual Image Buffer file, and is only
used while POV-Ray is rendering an image. So if for some reason you notice this large file left behind
after POV-Ray quits, it is OK - and suggested - that you delete it.
Credits and Blame
This Mac front end has a long and sordid history... I will tell you what I know.
Eduard Schwan created 2.0 by extensively modifying Jim Nitchals' 1.0 version, which was an extensive
modification of an earlier version written by Thomas Okken. A few other ideas were gleaned from an
even earlier Macintosh version built by Glenn Sugden. Mac things get awfully fuzzy and primordial
before that.
Dave Harr did the original 1.0 Balloon Help, helped design some user interface changes, and added the
custom palette code.
Jim Nitchals added the mini text editor with multiple undo, and invented the virtual image buffer swapping
code, and the first version of the PICT file saving package. Jim also improved the POV-Ray multitasking
and memory management (COOPERATE and POV_Malloc) to allow multiple renderings without having
to quit the program between renders. He also synthed up the ╥Done╙ boing sound.
Eduard [esp] Schwan ported the code from Think C 5 and built and tested it in MPW C, revamped the user
interface one more time (and had to continually rewrite Balloon Help to match), invented some code for a
generic status window that captured ╥printf╙s for both Think and MPW, got the AppleEvent stuff to work,
worked on the memory management, added QuickTime Image Compression, rewrote the prefs code,
added multi-file drag-n-drop, added the Mac animation support, retested and rebuilt the Think C 6 version,
re-worded this document, and bombarded Jim and other team members with late night calls, bug reports,
source changes, and wild suggestions.
Anton Raves relentlessly put the Beta POV-Ray 2.0 through its paces, and found all sorts of ╥unexpected
features╙ in the program. Many thanks for his tireless efforts, great suggestions, and imperceptible Dutch
accent!
Mark de Jong complained about all sorts of documentation and user interface abominations in the Beta 2.0
version, and really kept me on my toes.
Jim would like to thank his wonderful wife and best friend, Cindy, for her support while he was coding
and rendering many late nights. Thanks!
Eduard would like to thank Lorrie, Bryon, Sara, Sushi, and V.G.s (patient wife, impatient 5 year old son,
brand-new daughter, oblivious lap cat, and super donut shop) for sticking around while the bugs and
pixels were thickest.
Jim wishes there was a VG.'s nearby. They DO make the best donuts and also baked Cindy's and his
wedding cake.
Encore... more info please!
Where to get more info...
1. Refer to the POV-Ray documentation for general information on the scene description language, and
general theory of operation. This is contained in the included POVDOC archive.
2. For a superb in-depth discussion of the POV-Ray raytracer (version 2.2), you should get a copy of
the book, "Ray Tracing for the Macintosh CD", by Eduard Schwan, published by the Waite Group
Press, ISBN 1-878739-72-7...
blah blah...
3. For on-line information, new files, and technical support, join Compuserve's Graphics Developers
forum (GRAPHDEV), or America Online's Company Support area of the PC Graphics Forum
(keyword: "PGR").
4. There are many utility programs out there that convert files to POV-Ray format or create POV-Ray
objects. A handful of these utilities was ported to the Macintosh, and is on Compuserve and
America OnLine as the "Macintosh POV-Utilities", ported by Eduard [esp] Schwan. These are
worth checking out. Updates to these are planned in the near future.
5. For Macintosh-specific issues, please feel free to contact one of us directly:
Eduard [esp] Schwan can be reached on:
Compuserve: 71513,2161
Internet: 71513.2161@compuserve.com
US Mail: 1112 Oceanic Drive, Encinitas, California, USA, 92024-4007
(I check Compuserve every day or so. The Internet accounts are, as you can tell, simply gateways to my
Applelink or CIS accounts. Note that I am charged per kilobyte for any e-mail sent or received through the
internet gateway, so please don╒t send any large binhexed files unless you ask first.)
Note: When sending us questions via e-mail, we would like to assume that your question can be re-posted
publically in other online forums along with the reply. This way others can benefit from your experience.
If you don't want your question posted publicly, no problem, just let us know.
What's New
BIG NOTE: Only some of the POV-Ray archives have needed changes since version 2.0, the others are
remained at version 2.0. Here are the most current versions of each of the archives:
POVDOC.SEA - 2.0
POVMAC.SEA - 2.2
POVMNF.SEA - 2.2
POVSCN.SEA - 2.0
POVSRC.SEA - 2.2
What's new in version 2.2?
There were many complaints that POV-Ray's "SmartMalloc" progress between renders was between 5 and
10 minutes! This is due to 2 factors: The use of Mac memory management (instead of C memory
management), and the fact that auto-bounding was defaulted to ON which uses lots of memory. I have
temporarily returned to C's memory management, which is faster but __doesn't completely free up
memory__, and defaulted auto-bounding to be OFF. This is a temporary fix until we have no more
memory leaks in the code and can do away with SmartMalloc altogether (v3.0)!
Core bugs fixed: (See also "WHATSNEW.DOC")
- Fixed problem with declared material_maps or declared objects with
material_maps (yet again)
- Eliminated unnecessary turbulence calculations in normals
- Fixed all known problems with height fields
Mac-specific bugs squashed:
-SmartMalloc somewhat faster, for a price (see above)
-A few template bugs/aesthetics were fixed
-Insert Template now deletes any existing selection before inserting the template.
Core bugs fixed: (See also "WHATSNEW.DOC")
-some beziers crashing
-speckles on some surfaces with normal textures
-auto-bounding on Mac was read incorrectly and was always OFF
-Some Height fields had holes or rips in them, partially fixed.
Mac Notes
This document describes the specific functions of the Macintosh version of POV-Ray. It is assumed that
you have read (or will read) the POVRAY.DOC file that describes the general operation of POV-Ray.
The POV-Ray Preferences dialog, up close
This dialog sets up general preferences for the POV-Ray application that will be remembered between
renders, and between separate runs of POV-Ray itself. Here is a description of what each item does:
1. Application Friendliness - The higher the number, the more time POV-Ray takes from other
applications, and the faster it runs (and the slower and more jumpy the other applications become.)
2a. Use Application's Default Rendering Options - To use the Application Default Rendering Options for
rendering files (ignoring each file's unique Rendering Options), click here. This is normally used
for multiple rendering sessions.
The Rendering Options dialog, up close
This dialog sets up specific rendering options for the current scene file. These options are stored with the
scene file itself (in the respurce fork) and are remembered on subsequent renders of the scene file. Here is
a description of what each item does:
1a. Preset Image Sizes - Selecting an image size here will automatically fill in the width/height/from/to
fields below with a preset size. Many screen sizes are listed here.
1b. Width - Enter the total width of the image you want to render (in pixels.) This number can be from 1
to 4096.
(1c) Height - Enter the total height of the image you want to render (in pixels.) This number can be from 1
to 4096.
(1d) From row - Enter the top scanline, or starting row, of the image you want to render (in pixels.) Only
enter a number here if you want to render a partial image.
(1e) To row - Enter the bottom scanline, or ending row, of the image you want to render (in pixels.) Only
enter a number here if you want to render a partial image.
(2) Progress - Sets how much information is displayed in the status window as the render progresses.
"No Info" is quiet, "Minimal Info" shows some memory usage information, "Progress Info" informs you
of each scanline, "Debug Info" shows internal debug information. See POVRAY.DOC for more
information on the "+V" option.
(3) Image Quality - Enter a number (from zero to nine) to select the quality of the rendered image. 1 just
shows grey shapes, 5 shows colors, 9 shows full shadows lights and refraction. The lower the number,
the lower the quality and the faster the render.See POVRAY.DOC for more information on the "+Q"
option.
(4) Auto-bounding - Turn this popup on to let POV-Ray optimize your scene by automatically "bounding"
the objects in your scene. The number you set is the minimum number of main objects it finds before it
decides to kick in auto-bounding. See POVRAY.DOC for more information on the "+MB" option.
(5a) Animate - Turn this on if you want to create a sequence of multiple images from this scene file. See
POVRAY.DOC for more information on the "+K" option.
(5b) Animate Settings - Click this to set up the number of frames, clock value range, etc. for animation.
(6) Language - Set this to which version of POV-Ray syntax this file is written in (version 1.0 or 2.0.)
See POVRAY.DOC for more information on the "+MV" option.
(7a) Compress Image - Turn this on to automatically use QuickTime image compression on the output
PICT file when it is saved.
(7b) Compression Settings - Click this to set up what kind of image compression to use on the PICT file.
(8) Max Symbols - Set this to the largest number of #declared items in your scene file. See
POVRAY.DOC for more information on the "+MS" option.
(9a) Do Anti-aliasing - Click here to toggle ╥anti-aliasing╙ of the image. Although the rendering can take
much longer when this is on, the final image is much nicer looking, with fewer jagged edges. See
POVRAY.DOC for more information on the "+A" option.
(9b) Threshold - Enter a number here (from 0.0 to 1.0) that determines the threshold depth of anti-aliasing.
The closer to 0.0, the more anti-aliasing is done, the better the image looks, and the longer it takes to
render.
(9c) Depth - Enter a number from 1 to 9 here to set the recursive depth of anti-aliasing. The number of
rays is the square of this number, so a 3 would create 3*3 or 9 rays, etc.
(9d) Jitter - Enter a number from 0.0 (no jitter) through 1.0 (lots of jitter.) The higher this number, the
"wider" the anti-aliasing area, and the smoother it looks.
(10a) Create Targa Output File - To toggle the creation of a Targa-format output file during the render
process, click here. This can allow you to stop POV-Ray partway through, and run it later to finish from
where it left off.
(10b) Continue Rendering with Targa - To tell POV-Ray to load the Targa file from the previous run and
to continue where it left off last, click here.
(11) Save as defaults for new files - To save the current Rendering Option Settings as the Application's
Default Settings, click here. All new documents will then acquire these default Rendering Options.
The Animation Settings dialog, up close
This dialog sets up how many frames of animation to generate, and how the clock variable should change
across the frames. Note the outer bounds (Initial and Final) are used for calculating the overall number of
frames and values for the scene. The inner bounds (Start at and End at) are used to determine which
frames to actually generate for this session. Here is a description of what each item does:
*** Frame Number. This is just a reference number which counts the number of frames (or images) to
generate. It starts at one, and increments for each frame.
(1a) Initial - This is a constant low bound for the frame counter. It is always one.
(1b) Start At - This is the first frame number to start generating images for. It can be any integer number
from "Initial" to "End at".
(1c) End At - This is the last frame number to generate images for. It can be any integer number from
"End at" to "Final".
(1d) Final - This is the high bound for the frame counter. It is the total number of frames that should be
generated for the scene. This is used to calculate the span of clock values.
*** Clock Value. This is a variable passed into POV-Ray, which can be used as a dynamically changing
animation variable (clock) in a scene file.
(1a) Initial - This is the clock value at frame #1. It must be different than the "Final" clock value, but
otherwise may be any floating point value.
(1b) Start At - This is the displayed clock value at the "Start At" frame value.
(1c) End At - This is the displayed clock value at the "End At" frame value.
(1d) Final - This is the clock value at the "Final" frame #. It must be different than the "Initial" clock
value, but otherwise may be any floating point value.
Advanced Tips
To speed up rendering as much as possible on the Mac╔
If you are in the beginning stages of scene creation, you often find yourself editing, rendering, editing,
rendering, etc. To speed this up, try shrinking the image size to 32x32, and using the quick_color
statements and setting the Image Quality down to about 3. Also hiding the image window during
rendering speeds up POV-Ray a bit. If you are generating a final scene, try temporarily booting your Mac
with no (or few) extensions on. Some of these, especially screen savers and network connections, can
really slow things down. POV-Ray grabs more time if it is in the foreground, so don't switch it out
behind others. Also, choose the POV-Ray Preferences item from the Edit menu, and set the Application
Friendliness throttle way up, towards 11. Doing all of this can dramatically speed up the scene generation.
To edit large scene files╔
Because of the current file size limitation in the POV-Ray built-in editor, you must make sure that the main
╥.POV╙ file is no larger than 32K bytes. To edit and render larger files, you must use another text editor
to break the file into a small .POV file, which uses the #include statement to use the larger file(s). You can
then edit and render the .POV file with POV-Ray. The larger include files must still be edited with another
text editor. Note that if you use a word processor to do this (e.g. MacWrite, Word, WriteNow, etc.), you
must save the file in ╥Text-Only╙ format.
To batch-render a series of individual scene files╔
If you are rendering a few files of different output sizes/parameters, open each file in POV-Ray and set up
its ╥Rendering Options╙ the way you want, and close each file when done. There should be no POV-Ray
Source file window open now. Don't quit POV-Ray, but instead just switch to the System 7 Finder.
Select all the files which you just opened and set options for. Now drag them over onto the POV-Ray
application icon (or convenient application alias) and drop them on it. POV-Ray will (by default) render
each file with its own option settings, and save each image before starting the next.
If during this batch rendering process, you want to add more files to the list, just drag the new files onto
POV-Ray just like before. These new files will be added to the end of the list of files to batch-render.
To stop the batch rendering in progress, just choose "Stop Rendering" from the Render menu, or press
command-period. The current scene will be interrupted, and all remaining scenes will not render. To
resume, you will have to drop the remaining scene files onto POV-Ray again.
If you want a series of images to all be rendered, but with identical settings, then do this: Open any one of
the files to be rendered, and set up its Rendering Options the way you want all the files to be done. Now
choose ╥Application Preferences╙ from the File menu. Turn on the ╥Use Application Default Options╙
radio button, and turn on the ╥Save current file's rendering options as the default╙ checkbox, and click the
Save button. Close the source window, but DON'T QUIT POV-RAY YET! Now switch back to the
Finder, select all the files, and drag them onto the POV-Ray application icon, just like before. This time,
all the files will ignore their individual settings, and use the default application setting.
NOTE: In the interest of safety and user sanity, POV-Ray doesn't remember this override state, but always
returns to ╥╔each file's settings╔╙ when it is first run.
To generate a QuickTime movie from POV-Ray╔
Use the ╥clock╙ variable in expressions in your scene, to scale, translate, or rotate objects. Then use the
╥Rendering Options╙ menu item, turn on the ╥Animate╙ checkbox, and click the ╥Settings╙ button to set the
number of frames and the range of the clock variable. When you render the file, it will render multiple
times and generate a series of PICT files. You can then use MacroMind Director, Apple's Convert-to-
Movie, my FreeWare "MooVer" utility, or some other application to ╥import╙ the series of PICT files, and
save the result as a QuickTime movie.
To stop the animation rendering in progress, just choose "Stop Rendering" from the Render menu, or
press command-period. The current scene frame will be interrupted, and all upcoming frames will not
render.
To resume from some frame, you can choose "Animation Settings" from the Rendering Options dialog,
and set the "Start At:" to start where you left off. POV-Ray will then begin rendering from that frame to
the "End At:" frame.
An example of a spinning box and a moving sphere is shown below:
box { <-1,-1,-1> <1,1,1> rotate clock*y }
sphere { <0,0,0> 2 translate clock*z/36-5 }
If you set up the frames to go from 1 to 20, and the clock value to go from 0 to 360, then the above box
will make one complete revolution, and the sphere would move from -5 z to +5 z. The math is left as an
exercise to the reader :-)
Animation tip: If you are creating an animation that you want to smoothly loop, there is a subtle problem
you might run into. If you set up the animation to go from 0.0 to 360.0 degrees, you will notice that the
first and last frames are the same, since in the
"polar regions", zero is the same as 360. This means that at the loop point of the movie, there will be a
slight stall because the same frame is displayed twice. To get around this problem, you must do the
following:
Set the Final frame to be one more than you actually want (e.g., 101), and set the "End At:" frame at one
less than this (e.g., 100). Now set the "Start At:" frame number to 1, and set the Initial and Final clock
values to the full range (e.g., 0.0 to 360.0)... whew, now you are ready to make a movie! Of course, you
could just delete one of the frames and have a 99 frame movie, but that would be too easy.
How do I edit the Template file and add my own Templates?
The POV-Ray template importer reads a specially formatted text file, and builds a multi-level
(hierarchichal) menu structure, that connects specific menu items to blocks of text that can be automatically
inserted into the user's text file at the current cursor insertion point, simply by choosing that menu item.
The user imports the text once (or has it automatically imported every time they start POV-Ray). This
process builds the menu structure. Then whenever the user wants a particular item, he chooses it off the
TEMPLATES menu, and it is inserted into the current text file. Although the syntax and code of the
template reader can handle at least 4 menus deep, it is suggested to keep it down to 2 levels and group
things in a fairly flat and logical manner.
When the Import Template reader sees a command string in the form @xxx, starting in the first character
of the line, it reads the line as a command and processes it accordingly. The 4-character command is not
case sensitive, so "@mt1" and "@Mt1" are legal, though I would prefer to have them remain all lower
case. Note that empty lines are not skipped, they are added to the current menu item text. If this weren't
done, you couldn't add any blank lines as part of a template into your file. The side effect of this is that if
you want to separate items in the template file for legibility, you MUST use the @com comment
command.
COMMANDS
@com.Any text here...
This is a comment line, ignored by the parser.
@mt1.Title
This means define a new level-1 menu, and give it the name "Title". All level 2 menus will go under this
level 1 menu, until another level 1 menu is defined. There must not be anything else on these special lines.
@mt2.Title2
This means define a new level-2 menu (under a previously defined level 1 menu) and give it the name
"Title2". Any lines immediately following this line will be used as the text to be inserted. Blank lines are
valid and counted, so that the user can insert blank lines. The end of the text block is determined when the
next @xxx command is reached. Yes, I know you're thinking, "Oh good! I can define @mt3 & @mt4!"
Let's not do this, I don't think it is a good U.I. idea :-)
@@@@
This is an end-of-file mark, ignore anything after this in the file.
EXAMPLE
@mt1.Statements
@mt2.File Boilerplate
// Persistence of Vision Ray Tracer Scene description file
// File: ??.pov
// Version: 3
// Description: ??
// Date: mm/dd/yy
// Author: ??
//
@mt2.Background
// Set the color of the background (sky)
background { color red 0.1 green 0.3 blue 0.8 }
@mt2.Camera
// set viewer's position in the scene
camera
{
location <0, 1, -6> // <X Y Z>
direction 2.0*z // which way are we looking <X Y Z>
up y // which way is +up <X Y Z>
right 4/3*x // which way is +right <X Y Z> and aspect ratio
look_at <0, 0, 0> // point center of view at this point <X Y Z>
}
@mt1.Textures
@mt2.Pigment-rgb
pigment { color rgb <1,2,3> }
@mt2.Pigment-agate
pigment { agate agate_turb 1 }
@@@@
That was an eof token, so all this after it is ignored.
Bugs, Quirks, and Future Directions
The Bad News...
There is a maximum limit of 32,000 characters (approx. 32K bytes) in source files in the built-in text
editor window. The text editor will not allow you to open or create files bigger than this. This is due to a
limitation of the Macintosh TextEdit package (i.e., Programmer Laziness.) Although the main file to be
rendered must be less than 32K in size, any #included (.INC) files may be of any size. You will just need
to use some other editor or word processor to edit those. If you do use a word processor to edit them,
remember to save your files in TEXT-only format.
There is this same 32K limit in the Status window text. When the Status Window gets close to this limit,
it just drops things off the top as it adds to the bottom. So you always have the last 32K of text in the
window.
If you create and render a scene file with nothing in it, it will display an error "no objects found in scene."
If you try to run the same scene again, you will get some odd error messages.
After each rendering job, POV-Ray "loses" about 1 KByte of RAM memory. This sloppy phenomenon,
sometimes known in programming circles as a "memory leak", is not harmful. However, after you've
done a large number of renders without quitting the application, you may eventually get an "out of
memory" error. Just quit and restart POV-Ray, and it will be fine for awhile again. This will be more of a
problem if you are doing animation renders with lots of frames. You may have to break it into multiple
runs, or increase POV-Ray's application heap size. This was addressed prior to release, but not all leaks
were found... it will be completely fixed in a future release. All "direct" memory leaks are fixed, what's
left seems to be caused by calling runtime routines that themselves leak.
POV-Ray should be creating the POV-Ray Virtual Image Buffer file in the Temporary Items folder if it is
running under System 7, it currently does not.
There is still an occasional quirk in the vertical scrollbar of the Status window, where it will get out of
sync if you scroll it while the window is being filled. Nothing is lost, and if you scroll to the top and back
to the bottom, all returns to normal.
There are reports that the "Finder Balloon Help" of the POV-Ray Application (turn on Balloon Help and
point at app in the Finder) does not work on some Macs. It will report a Finder "Type -192" error. It
seems to work properly on other machines. This may be due to a corrupt desktop database, although
rebuilding the desktop was reported not to help.
Under System 6.x, POV-Ray will not automatically open a document that is double clicked from the
Finder. You must run POV-Ray, then open the file from the File menu. Double-clicking documents
DOES work properly in System 7, and in fact, multiple file drag-n-drop is supported. This missing
System 6 feature was an intentional omission due to time constraints and the low priority of the feature.
If you are using a virtual image buffer for a large image, it is not advisable to use the "Size Image to
Window" mode, because the image won't display properly. This is only a display problem, It will save
properly when finished.
Adobe Photoshop prior to version 2.5 ignores the vertical-flipped bit of the TARGA files created by POV-
Ray, and displays them upside down. Version 2.5 fixes this problem.
With System 7 Virtual Memory (VM) on, and anti-alias setting on, and an anti-alias on, the VM file will do
some thrashing occasionally if your rendering requires a virtual image buffer. This will just slow things
way down; it doesn't cause any crashes.
The Good News
Coming sometime after version 3.0...
* Allow selecting an arbitrary area in Image window, and then re-rendering just that area (x1,y1 to
x2,y2).. more flexible than the current start/end scanline method
* Allow user to scroll the Image window
* Let user pick file signature for PICT and Targa file formats. Currently, PICT files are saved with
TeachText's signature and Targa files are saved with PhotoShop's (PICT creator type is currently saved in
scene file's fPrf resource, & could be edited with ResEdit.)
* Built-in QuickTime movie support
* TIFF and PICT image (image-map) support for POV-Ray
* TrueType font support (extruded characters.. need generic POV-Ray syntax additions for typeface
import?)
* Allow saving image directly to GIF or 8 bit Mac PICT format (currently just 24 bit PICT now.)
* Mac Network (distributed) rendering
The Mac Source Editor needs a _major_ facelift, to include:
* Abandon stock TextEdit, support source files larger than 32K chars
* Support tabs
* Search and replace features should be added
* Shape prototype generation, esp. torus and other tough ones
* Add balanced curly brace checking
* Simultaneously edit multiple source files, useful for Includes
One possible way to enhance the editor is to give up on the built-in text editor altogether, and tell the user
to use BBEdit or some other text editor, and we could break POV-Ray into a faceless rendering engine that
accepts AppleEvents. The options dialogs could be supported by a stand-alone application that could alter
the file's settings prior to rendering. This makes POV-Ray more loosely coupled, but paves the way for
drop-in editors and network rendering. Besides the time it would take to do this, an interesting obstacle to
overcome is how the rendering engine would display its image. If it was not so tightly integrated, quick
changes and re-rendering sessions may be more awkward. These are some interesting ideas... we are
interested in hearing from users as to which way future versions of POV-Ray should head, let us know!
The Source Code
POV-Ray is a team effort, and the team members use Compuserve's Graphics Developers forum
(GRAPHDEV) to keep abreast of changes and suggestions. Before you jump in and write massive
enhancements, we suggest that you contact any of the team members and get to know the guidelines. We
are an easy going bunch, and very friendly and interested in helping newcomers. And who knows, we
may be working on the very same features you want to add, or your enhancement may be one we're
hoping to see done.
Before you publically post altered source or executables, please review the POV-Ray legal documentation
for copyright restrictions and rules of distribution. POVLEGAL.DOC can be found in any of the archives.
To restate our position: please contact us directly with any bug fixes or enhancements. We can then
incorporate them into the next general release.
The executables released by the POV Team for the Macintosh are built using Think C 6.0. It is possible to
create even faster POV-Ray executables using a mix of Gnu C and MPW, but for a straight compilation,
Think C 6.0 is a little smaller and faster than MPW 3.2 or MPW 3.3.
You will find the source code in two sections in the POVSRC archive. The main portion of POV-Ray is in
POVSRC:SOURCE:. The additional Macintosh-specific source code is in POVSRC:MACHINE:MAC-
Source:. These two sets of source should then be put together into a single POV-Ray Source folder before
building (any name is fine.)
Think C Compiler Notes
When compiling, you must use Think C 7.0 or later.
You should first make a COPY of your "Standard Libraries:ANSI" library's Project file, and rename your
copy to ╥ANSI.020.FPU╙. This will be the ANSI library you'll be using for POV-Ray. Choose the
Edit:Options menu, and change the following: Think C:Compiler settings, turn on all checkboxes except
"4 byte ints" and "8 byte Doubles". In Code Optimizations:turn on all, but not the Global Optimizations.
Debugging:turn off all. Prefix:add a #define _NOCONSOLE_. Choose the menu Project:Set Project
Type, and turn on "Separate Strs". Now "update" to compile all the modules.
Here are the additional steps to create the POV.╣ project file from scratch. Start up Think C, create a new
project called POV.╣, and add all the .c source files to the project. Here's the current segmenting strategy:
=== Segment (povNEditor) ===
FileQueue.c
POV.c
POVMalloc.c
ScreenUtils.c
TextEditor.c
=== Segment (textures) ===
pigment.c
texture.c
txttest.c
=== Segment (tokenize) ===
express.c
matrices.c
tokenize.c
=== Segment (macwindows) ===
animate.c
imagewindow.c
popupmenu.c
printf2window.c
progressdialog.c
savecmppict.c
stdcompressionglue.o
templatemenu.c
=== Segment (files) ===
dump.c
gif.c
gifdecod.c
iff.c
raw.c
targa.c
=== Segment (parse) ===
parse.c
=== Segment (render) ===
normal.c
povray.c
ray.c
render.c
vect.c
=== Segment (polyquad) ===
poly.c
quadrics.c
=== Segment (heightfields) ===
hfield.c
=== Segment (cameraNlights) ===
camera.c
lighting.c
=== Segment (primparse) ===
boxes.c
colour.c
csg.c
image.c
objects.c
planes.c
point.c
=== Segment (primparse2) ===
blob.c
bound.c
cones.c
discs.c
=== Segment (primparse3) ===
spheres.c
triangle.c
=== Segment (bezier) ===
bezier.c
=== Segment (ansi) ===
ANSI-020.FPU.NoConsole
MacTraps
MacTraps2
Choose the Edit:Options:Think C: menu, and change the following: Language:turn on Check Pointer
Types and Think C Language Extensions. Compiler settings, turn on all checkboxes except "4 byte ints"
and "8 byte Doubles". Code Optimizations:turn on all. Debugging:turn off all. Prefix:add a #define
_NOCONSOLE_. Choose the menu Project:Set Project Type, and turn on "Separate Strs", set the Creator
to "PvRy", set the Size Flags to 58E0, set the type to Application, and set the Partition to 1000. Insert the
following into the Prefix options from the Edit menu:
#define SystemSixOrLater true
#define _NOCONSOLE_ // turn off Think C console I/O
#include <MacHeaders>
#define NEEDS_68020 1 // turn on to force 68020 or better CPU code
#define NEEDS_COLORQD 1 // turn on to force Color Quickdraw ROM Support
#define NEEDS_32BITQD 1 // turn on to force 32Bit Quickdraw ROM Support
#define NEEDS_FPU 1 // turn on to force 68881 FPU calls
#define USE_NATIVE_MALLOC 1 // turn off to use C's malloc(), on for Mac's NewPtr()
After you build the application, you must set the application's (preferred) memory size to 2500, using the
Finder's "Get Info" menu item. This is currently the only way to set the minimum and preferred memory
sizes differently.
MPW C Compiler Notes
The non-FPU version of POV-Ray was compiled under MPW, because the code generated was too big for
Think C (specifically, hfield.c.) An MPW compile of the FPU version of POV-Ray is possible, but
generates a noticeably larger and slower application.
POV-Ray has been compiled and tested using Apple's MPW C compiler, 3.3.1 The make file supposedly
supports MPW 3.2 as well, but has not been tested.
In order to compile POV-Ray with the included make file, you will first need to manually create an empty
folder inside the POV-Ray Source folder called ╥obj╙. The object files will be stored in there, instead of
being sprinkled through the source code folder.
There are quite a few flags used to turn on and off options (FPU, native-malloc, etc.), these are in the
Make file itself.
There are some warnings that show up in the POV-Ray core code, all of them are due to unused function
parameters. These are, in the immortal words of Douglas Adams, ╥Mostly Harmless.╙
Metrowerks Compiler Notes